PC Users 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ PC Users 1998 November / Cd users extra 14.iso / prog / inst / mailc / see4c_r.txt < prev next >

Wrap

Text File | 1998-09-14 | 30.3 KB | 1,082 lines

SMTP/POP3 Email Engine Library for C/C++ (SEE4C) REFERENCE MANUAL Version 2.0 September 14, 1998 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1998 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 256-881-4630 FAX : 256-880-0925 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER MARSHALLSOFT is a registered trademark of MarshallSoft Computing. SEE4C Reference Manual Page 1 C O N T E N T S Chapter Page Table of Contents.............................2 General Remarks...............................3 SEE Functions.................................3 seeClose...................................3 seeDeleteEmail.............................4 seeDriver..................................5 seeErrorText...............................6 seeExtractText.............................7 seeGetEmailCount...........................8 seeGetEmailFile............................9 seeGetEmailLines..........................10 seeGetEmailSize...........................11 seeIntegerParam...........................12 seePop3Connect............................13 seeSendEmail..............................14 seeSmtpConnect............................15 seeStatistics.............................16 seeStringParam............................17 seeVerifyFormat...........................18 SEE4C Reference Manual Page 2 General Remarks All functions return an integer code. Negative values are always errors. See Section 10.3 "SEE Error Return Code List" in the SEE/POP3 Users Manual (SEE4C_U.TXT). Non-negative return codes are never errors. Allocate all buffers passed to SEE statically, rather than dynamically on the stack. You can always force any variable declaration to be staticly allocated by use of the "static" keyword, for example: static char Buffer[64]; SEE Functions +----------+--------------------------------------------------------+ | seeClose | Closes SMTP/POP3 Email Engine. | +----------+--------------------------------------------------------+ SYNTAX int seeClose(void) REMARKS The seeClose function closes the connection created by calling seeSmtpConnect or seePop3Connect. seeSmtpConnect or seePop3Connect can be called again to open a connection to another SMTP or POP3 server if desired. SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate the connection before connecting again. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE // call after sending all email. seeClose(); ALSO SEE seeSmtpConnect and seePop3Connect. SEE4C Reference Manual Page 3 +----------------+--------------------------------------------------+ | seeDeleteEmail | Deletes email from Server. | +----------------+--------------------------------------------------+ SYNTAX int seeDeleteEmail( int MsgNbr) // message number REMARKS The seeDeleteEmail function deletes the email numbered 'MsgNbr' from the server. After each email deletion by the POP3 server, all messages are renumbered, the first message being 1. Therefore, delete messages from highest to lowest to avoid having to recalculate message numbering. For example, to delete messages 5, 6, and 7, message 7 is deleted first, then message 6, and lastly message 5. Be careful! Once an email has been deleted from the server, it cannot be recovered. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE int Code; . . . // delete message # 5 , # 6, and #7. Code = seeDeleteEmail(7); if(Code>=0) Code = seeDeleteEmail(6); if(Code>=0) Code = seeDeleteEmail(5); . . . ALSO SEE seeGetEmailCount. SEE4C Reference Manual Page 4 +-----------+-------------------------------------------------------+ | seeDriver | Executes next SEE state. | +-----------+-------------------------------------------------------+ SYNTAX int seeDriver(void) REMARKS The seeDriver function executes the next state in the SEE state engine. The purpose of this function is to allow the programmer to get control after the driver executes each state. The seeDriver function is explicitly called only after the AUTO_DRIVER_CALL flag has been disabled (see function seeIntegerParam). If the AUTO_DRIVER_CALL flag has not been disabled (the default), then seeDriver is never called. Refer to the section 4.0 "Theory of Operation" in the SMTP/POP3 Users Manual for more details on the operation of seeDriver. RETURNS = 0 : The driver is done. < 0 : An error has occurred. See the error list. > 0 : The returned value is the state just executed. EXAMPLE int Code; . . . [call seeSmtpConnect] . . . // disable automatic calling of seeDriver(). seeIntegerParam(AUTO_DRIVER_CALL, 0); Code = seeSendEmail(...); if(Code<0) {printf("Error %d\n", Code); exit(1); } while(1) {Code = seeDriver(); if(Code<0) {printf("Error %d\n", Code); exit(1); } /* display all but "wait" state */ if(Code!=9999) printf("%d ",Code); if(Code==0) return 0; } } ALSO SEE seeIntegerParam, seeSmtpConnect, and seePop3Connect. SEE4C Reference Manual Page 5 +--------------+----------------------------------------------------+ | seeErrorText | Get text associated with error code. | +--------------+----------------------------------------------------+ SYNTAX int seeErrorText( int Code, // Error code returned by SEE function. LPSTR Buffer, // Buffer to place error text into. int BufLen) // Length of above Buffer. REMARKS The seeErrorText function is used to get the error text associated with an an error code as returned by one of the other SEE functions. When an error occurs, seeErrorText can be used to get the error text so that it can be displayed for the user. RETURNS < 0 : An error has occurred. See the error list. >=0 : Error message was copied into 'Buffer'. EXAMPLE static char Buffer[80]; . . . Code = seeSmtpConnect( "mail.myisp.net", // SMTP server "<me@myisp.net>", // your email address NULL); // reply-to if(Code<0) {seeErrorText(Code,Buffer,80); printf("ERROR %d: %s\n", Code, Buffer); exit(1); } SEE4C Reference Manual Page 6 +----------------+--------------------------------------------------+ | seeExtractText | Extract specified text from buffer. | +----------------+--------------------------------------------------+ SYNTAX int seeExtractText( LPSTR Src, // Text buffer to search. LPSTR Text, // Text searching for. LPSTR Buffer, // Buffer for line if found. int BufSize) // Size of 'Buffer'. REMARKS The seeExtractText function is used to search the text buffer 'Src' for text 'Text'. If found, the entire line is copied to 'Buffer', up to a maximum of 'BufSize' bytes. The primary purpose of seeExtractText is to extract header lines from the buffer after calling seeGetEmailLines. The seeExtractText does not require a connection to a SMTP or POP3 server. For an example of use, see the STATUS and FROM sample programs. RETURNS 1 (TRUE) if 'Text' was found 0 (FALSE) if 'Text' was not found. EXAMPLE // search 'Source' for the line containing "From:" Code = seeExtractText((LPSTR)Source,(LPSTR)"From: ", (LPSTR)Temp, 80); // print line if found if(Code>0) printf("%s\n", Temp); ALSO SEE seeGetEmailLines. SEE4C Reference Manual Page 7 +------------------+------------------------------------------------+ | seeGetEmailCount | Get number of email messages on server. | +------------------+------------------------------------------------+ SYNTAX int seeGetEmailCount(void) REMARKS The seeGetEmailCount function returns the number of messages waiting on the server, independent of whether they have been previously read. If you have disabled the driver AUTO_CALL capability, the message count must be found by Count = SioStatistics(SEE_GET_MSG_COUNT) after calling SioDriver until it returns 0. Refer to the STAT and STATUS sample program for examples of use. RETURNS < 0 : An error has occurred. See the error list >=0 : The number of email messages waiting (if AUTO_CALL was disabled). EXAMPLE /* connect to POP3 server */ Code = seePop3Connect( (LPSTR)"mail.myisp.net", // POP3 server (LPSTR)"billbob", // user (LPSTR)"xxx"); // password /* get # messages waiting */ Code = seeGetEmailCount(); printf("%d messages waiting\n",Code); ALSO SEE seeGetEmailLines. SEE4C Reference Manual Page 8 +-----------------+-------------------------------------------------+ | seeGetEmailFile | Read email message & save to a file. | +-----------------+-------------------------------------------------+ SYNTAX int seeGetEmailFile( int MsgNbr, // header # LPSTR EmailName, // email filename LPSTR EmailDir, // directory for email LPSTR AttachDir) // directory for attachments REMARKS The seeGetEmailFile reads the email message 'MsgNbr', saving it to disk as filename 'EmailName' in directory 'EmailDir', and saving MIME attachments to directory 'AttachDir'. The current directory is specified as '.'. RETURNS < 0 : An error has occurred. See the error list EXAMPLE // read message 1 and save as MYMAIL.TXT in // current directory Code = seeGetEmailFile(1, (LPSTR)"mymail.txt", (LPSTR)".", (LPSTR)"."); ALSO SEE seeGetEmailLines. SEE4C Reference Manual Page 9 +------------------+------------------------------------------------+ | seeGetEmailLines | Read lines from email message. | +------------------+------------------------------------------------+ SYNTAX int seeGetEmailLines( int MsgNbr, // message # int Lines, // # lines LPSTR Buffer, // Pointer to (static) Buffer int Size) // size of buffer REMARKS The seeGetEmailLines function reads all header lines plus the number of body lines specified by the 'Lines' argument into 'Buffer', up to a maximum of 'Size' bytes. The primary purpose of this function is to read the header lines without having to read the entire message. If you have disabled the driver AUTO_CALL capability, the size must be found by Count = SioStatistics(SEE_GET_BUFFER_COUNT) after calling SioDriver until it returns 0. See the STATUS and FROM sample code for examples of use. RETURNS < 0 : An error has occurred. See the error list. >=0 : The number of bytes read (if AUTO_CALL was disabled). EXAMPLE char Buffer[1024]; . . . /* read header lines for email # 1 */ Code = seeGetEmailLines(1,0,(LPSTR)Buffer,1024); ALSO SEE seeGetEmailFile SEE4C Reference Manual Page 10 +-----------------+-------------------------------------------------+ | seeGetEmailSize | Get size of email message in bytes. | +-----------------+-------------------------------------------------+ SYNTAX long seeGetEmailSize( int MsgNbr) // message number REMARKS The seeGetEmailSize function returns the size in bytes of the specified message # 'MsgNbr'. seeGetEmailSize returns the size of the entire email message, including any attachments. Note that attachments will be encoded (MIME, UUENCODE, etc.), and thus take up more room than after they are decoded. If you have disabled the driver AUTO_CALL capability, the size must be found by Count = SioStatistics(SEE_GET_MSG_SIZE) after calling SioDriver until it returns 0. See the READER sample code for an example of use. RETURNS < 0 : An error has occurred. See the error list >=0 : The size of the email in bytes on the server (if AUTO_CALL was disabled). EXAMPLE long FileSize; . . . /* get size of email message # 3 */ FileSize = seeGetEmailSize(3); ALSO SEE seeGetEmailCount. SEE4C Reference Manual Page 11 +-----------------+-------------------------------------------------+ | seeIntegerParam | Sets SEE integer parameter. | +-----------------+-------------------------------------------------+ SYNTAX int seeIntegerParam( int ParmIndex, // Parameter index (see below). ULONG ParmValue) // Value of parameter to set. REMARKS The seeIntegerParam is used to set an integer parameter as defined in SEE.H. For more information, refer to the Users Manual. All times are in milliseconds. Parameter Name Default SEE_MIN_RESPONSE_WAIT : 500 SEE_MAX_RESPONSE_WAIT : 10000 SEE_MIN_LINE_WAIT : 5 SEE_MAX_LINE_WAIT : 10000 SEE_CONNECT_WAIT : 60000 SEE_QUOTED_PRINTABLE : 0 SEE_AUTO_CALL_DRIVER : 1 SEE_MIN_RESPONSE_WAIT is the delay before looking for the server's response. SEE_MAX_RESPONSE_WAIT is the time after which a "time-out" error occurs if the server has not responded. SEE_MIN_LINE_WAIT is the delay before checking if the server is ready to accept the next line of input. SEE_MAX_LINE_WAIT is the time after which a "time-out" error is declared if the server has not responded. SEE_CONNECT_WAIT is the maximum time allowed to complete a connection to the SMTP server. SEE_QUOTED_PRINTABLE controls whether messages are (1) or are not (0) encoded as quoted-printable. SEE_AUTO_CALL_DRIVER controls whether seeDriver is called automatically (to completion) after seeSmtpConnect or seePop3Connect has been called. EXAMPLE /* disable auto call feature */ seeIntegerParam(SEE_AUTO_CALL_DRIVER, 0); ALSO SEE seeStringParam. SEE4C Reference Manual Page 12 +----------------+--------------------------------------------------+ | seePop3Connect | Connects to POP3 Server. | +----------------+--------------------------------------------------+ SYNTAX int seePop3Connect( LPSTR Pop3Ptr, // POP3 server name LPSTR UserPtr, // POP3 user name. LPSTR PassPtr) // POP3 password. REMARKS The seePop3Connect function establishes a connection with the POP3 server as specified by the Server argument. Your POP3 server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your POP3 server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook. The POP3 server name can also be specified in dotted decimal notation if wanted. For example "10.23.231.1". SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate the connection before connecting again. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE int Code; Code = seePop3Connect( (LPSTR)"mail.myisp.com", // POP3 server (LPSTR)"billbob", // user (LPSTR)"xxx"); // password ALSO SEE seeSmtpConnect and seeClose. SEE4C Reference Manual Page 13 +--------------+----------------------------------------------------+ | seeSendEmail | Sends email and attachments. | +--------------+----------------------------------------------------+ SYNTAX int seeSendEmail( LPSTR To, // Recipient, separated by commas. LPSTR CC, // CC list, separated by commas. LPSTR BCC, // BCC list, separated by commas. LPSTR Subj, // Subject text. LPSTR Msg, // Message or message filename. LPSTR Attach) // File attachment. REMARKS The seeSendEmail function is used to send email once a connection has been made to your SMTP server after calling seeSmtpConnect. Note that all email addresses (in To, CC, and BCC strings) must be bracketed. For example: <mike@marshallsoft.com> The CC and BCC strings may contain multiple email addresses, separated by commas. For example: "Billy Bob<bbob@isp.com>,Buster<bm@isp.com>" If the first character of the message (fifth argument) is a '@', then it is considered as the filename which contains the message to send. 'Attach' may contain one or more attachments, separated by commas. For example, "file1.zip,file2.doc". RETURNS < 0 : An error has occurred. See the error list. EXAMPLE seeSendEmail("<myfriend@hisisp.com>", /* recipient */ NULL, /* CC list */ NULL, /* BCC list */ "Hello", /* subject */ "Call me ASAP!", /* message */ NULL); /* attachment */ ALSO SEE seeSmtpConnect. SEE4C Reference Manual Page 14 +----------------+--------------------------------------------------+ | seeSmtpConnect | Connects to SMTP server. | +----------------+--------------------------------------------------+ SYNTAX int seeSmtpConnect( LPSTR Server, // SMTP server. LPSTR From, // Your email address in brackets. LPSTR ReplyTo) // Email address to reply to. REMARKS The seeSmtpConnect function establishes a connection with the SMTP server as specified by the 'Server' argument. Your SMTP server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your SMTP server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook. The SMTP server name can also be specified in dotted decimal notation if wanted. For example "10.23.231.1". The 'From' string is required and must be enclosed in "<>" brackets, such as <mike@marshallsoft.com>. The 'ReplyTo' string is optional and is used for the "Reply-To:" header line. If used, the email address must be enclosed in "<>" brackets. SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate the connection before connecting again. RETURNS < 0 : An error has occurred. See the error list. EXAMPLE seeSmtpConnect("mail.myisp.com", // my SMTP server "<me@myisp.com>", // my email address NULL); // no Reply-To seeSmtpConnect("mail.myisp.com", // my SMTP server "<me@myisp.com>", // my email address "<him@himisp.com>); // Reply-To address ALSO SEE seeClose. SEE4C Reference Manual Page 15 +---------------+---------------------------------------------------+ | seeStatistics | Returns runtime statistics. | +---------------+---------------------------------------------------+ SYNTAX ULONG seeStatistics( int Index) // Specifies which statistic. REMARKS The seeStatistics function is used to return runtime statistics in the SEE DLL. The values of 'Index' are defined in SEE.H as follows: SEE_GET_VERSION : Gets the SEE version number. SEE_GET_SOCK_ERROR : Gets last socket error. SEE_GET_COUNTER : Gets # times driver called. SEE_GET_RESPONSE : Gets last SMTP response code. SEE_GET_MESSAGE_BYTES_READ : Gets # message bytes read. SEE_GET_ATTACH_BYTES_READ : Gets # attachment bytes read. SEE_GET_TOTAL_BYTES_READ : Gets total of above two. SEE_GET_MESSAGE_BYTES_SENT : Gets # message bytes sent. SEE_GET_ATTACH_BYTES_SENT : Gets # attachment bytes sent. SEE_GET_TOTAL_BYTES_SENT : Gets total of above two. SEE_GET_MSG_COUNT : Gets # emails waiting. SEE_GET_MSG_SIZE : Gets size of email. SEE_GET_BUFFER_COUNT : Gets # bytes in buffer for seeGetEmailLines. The number of message bytes sent will usually be larger than your message size because of SMTP protocol overhead. The number of attachment bytes sent will be at least one-third larger than the actual attachment since every 3 bytes are encoded as 4 7-bit ASCII bytes before being transmitted. The purpose of "...BYTES_READ" and "...BYTES_SENT" is to provide the ability to track the transmission progress of large messages and attachments. See the READER example program. EXAMPLE // get total message & attachment bytes transmitted. Code = seeStatistics(SEE_GET_TOTAL_BYTES_SENT); ALSE SEE seeDriver, seeIntegerParam, and seeStringParam. SEE4C Reference Manual Page 16 +----------------+--------------------------------------------------+ | seeStringParam | Sets SEE string parameter. | +----------------+--------------------------------------------------+ SYNTAX int seeStringParam( int ParamName, // Index of parameter. LPSTR ParamString) // Parameter string. REMARKS The seeStringParam function is used to set a string parameter as defined in SEE.H. For more information, refer to the Users Manual. SEE_LOG_FILE : Specifies the log filename. The log file is used to debug a SMTP session. Be advised that log files can be quite large. Don't use them unless necessary. EXAMPLE seeStringParam(SEE_LOG_FILE, "mytest.log"); ALSO SEE seeIntegerParam. SEE4C Reference Manual Page 17 +-----------------+-------------------------------------------------+ | seeVerifyFormat | Check email address format. | +-----------------+-------------------------------------------------+ SYNTAX int seeVerifyFormat( LPSTR String) // Email address to check. REMARKS The seeVerifyFormat function is used to test an individual email address for proper formatting. If this function returns 0 or above, then the email address is properly formatted. But, if this function returns a negative value, the email address is either badly formatted, or it uses characters (such as '%') that are not normally used as part of an email address. Note that left and right brackets ('<' and '>') must surround the email address. EXAMPLE static char Buffer[80]; . . . Code = seeVerifyFormat("Billy E. Bob<beb@hisasp.com>"); if(Code<0) {seeErrorText(Code,Buffer,80); printf("Email address error : %s\n", Buffer); exit(1); } ALSO SEE seeErrorText. SEE4C Reference Manual Page 18